External API messages (transactional) are used to send trigger messages to contacts based on events external to Lyris. An example of using the External API is when you are tracking a transaction occurring on your Web site. The External API enables you to use the API to initiate a trigger message send.
First you need to define your trigger message as one that can be used with an External API.
1. Navigate to the Define Triggers screen.
2. In the Triggering Action box, click on the Add Trigger Action or condition text link under Change Order.
3. Pick External API on the drop down menu.
4. You cannot add any conditions to the External API trigger message. These will be in the external system.
In order to use the External API to send a triggered message, you will first need to identify the Message Id, List Id, and Trigger Id to use in the API.
1. Click on the Configure Columns icon in the upper left hand corner of the Email Marketing – Messages screen.
2. Select List Id and then Trigger Id at the bottom of the drop down menu.
This displays the List Id and Trigger Id in the new corresponding columns. The Trigger Id and List Id are used by the External API to identify which message you want to send, along with the Message Id.
The Site Id identifies the Org that the message is in and is needed for the external API.
1. Click the Settings text link in the upper hand corner of Lyris HQ, in order to identify the Site Id.
2. Click on the org you want to access within the Organizations box.
The Site Id is listed under Organization details, as outlined in red below.
Generate a script to utilize the API call. The API call data is below:
Transfers data to enable a transactional message to be sent from an external system.
Trigger_id[required]
Tells the system which trigger stub to use for reporting and default message (if using). (The Trigger Id can be obtained from the Email Marketing Messages > Trigger Id column in LHQ.)
Recipients[requiredl]
Comma delimited list of email address to receive email. Can be one address or many.
Recipients_data[optional]
Location of CSV or TXT file with large list of recipients. Must be in URL format(http://example.com/data.csv)
Subject[optional]
Subject of the message if not using the default specified in the user interface.
From_email[optional]
From email address to use in the message envelope if not using the default specified in the user interface.
From_name[optional]
YYYY-MM-DD - Limits the results to this end date
Tracking[optional]
Enabled open and click tracking for the message (if not using the default message specified in the user interface)
Message[optional]
URL of location to fetch HTML content or actual raw HTML (URL encoded).
| Parameter | Req? | Type | ID | Value |
| Site_ID | Yes | N/A | N/A | (Site ID of account) |
| MLID | Yes | N/A | N/A | (Mailing list ID of trigger) |
| trigger_ID | Yes | Extra | trigger_ID | (id of trigger) |
| recipients | No | Extra | recipients | (single or comma delimited list of recipients) |
| recipient_data | No | Extra | recipient_data | (URL location of CSV file with recipients) |
| subject | No | Extra | subject | (Subject Line) |
| from_email | No | Extra | from_email | (From Email Address) |
| from_name | No | Extra | from_name | (From Name) |
| tracking | No | Extra | tracking | on |
| message content | Yes | Extra | message | URL of location to fetch html or full HTML |
Example: skip_blacklisted set, some blacklisted recipients
This example shows that if the parameter skip_blacklisted is set, no messages will be sent to the blacklisted recipients and they will not appear in the sent list.
Input:
<DATASET>
<SITE_ID>3</SITE_ID>
<MLID>8</MLID>
<DATA TYPE="EXTRA" ID="TRIGGER_ID">4</DATA>
<DATA TYPE="EXTRA" ID=" SKIP_BLACKLISTED ">ON</DATA>
<DATA TYPE="EXTRA" ID="RECIPIENTS">jdoe-1@im.example.com,jdoe-2@im.example.com,jdoe-black1@im.example.com,jdoe-black2@im.example.com</DATA>
</DATASET>
Output:
<DATASET><TYPE>success</TYPE><DATA> type="sent">jdoe-1@im.example.com,jdoe-2@im.example.com</DATA>im.example.com, jdoe-black2@im.example.com</DATA>
<DATA> type="not sent"/>
<DATA type="blacklisted">jdoe-black1@
</DATASET>
NOTE:You can utilize the default message in the trigger if you choose. Simply send only the trigger ID and the recipient information.
NOTE: You can send a single recipient or a comma delimited list of recipients. You can also send a CSV file of recipients via a web location.
NOTE: You can use personalization inside the message being sent along; simply use the existing mail merge tags or dynamic content.
Click here to go to back to the Lyris HQ Triggers Overview.